home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Languguage OS 2
/
Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO
/
gnu
/
elispman.lha
/
elispman
/
elisp-33
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1993-05-11
|
51KB
|
786 lines
This is Info file elisp, produced by Makeinfo-1.52 from the input file
elisp.texi.
This file documents GNU Emacs Lisp.
This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
Emacs Version 19.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1990, 1991, 1992 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: elisp, Node: Selective Display, Next: Overlay Arrow, Prev: The Echo Area, Up: Emacs Display
Selective Display
=================
"Selective display" is a class of
minor modes in which specially marked lines do not appear on the
screen, or in which highly indented lines do not appear.
The first variant, explicit
selective display, is designed for use in a Lisp program. The program
controls which lines are hidden by altering the text. Outline mode
uses this variant. In the second variant, the choice of lines to hide
is made automatically based on indentation. This variant is designed
as a user-level feature.
The way you control explicit
selective display is by replacing a newline (control-j) with a
control-m. The text which was formerly a line following that newline
is now invisible. Strictly speaking, it is temporarily no longer a
line at all, since only newlines can separate lines; it is now part of
the previous line.
Selective display does not
directly affect editing commands. For example, `C-f' (`forward-char')
moves point unhesitatingly into invisible space. However, the
replacement of newline characters with carriage return characters
affects some editing commands. For example, `next-line' skips
invisible lines, since it searches only for newlines. Modes that use
selective display can also define commands that take account of the
newlines, or which make parts of the text visible or invisible.
When you write a selectively
displayed buffer into a file, all the control-m's are replaced by their
original newlines. This means that when you next read in the file, it
looks OK, with nothing invisible. The selective display effect is seen
only within Emacs.
- Variable: selective-display
This buffer-local variable
enables selective display.
This means that lines, or
portions of lines, may be made
invisible.
* If the value of
`selective-display' is
`t', then any portion of a
line that follows a
control-m is not displayed.
* If the value of
`selective-display' is a
positive integer, then
lines that start with more
than `selective-display'
columns of indentation are
not displayed.
When some portion of a buffer
is invisible, the vertical
movement commands operate as if
that portion did not exist,
allowing a single `next-line'
command to skip any number of
invisible lines. However,
character movement commands
(such as `forward-char') do not
skip the invisible portion, and
it is possible (if tricky) to
insert or delete text in an
invisible portion.
In the examples below, what is
shown is the *display* of the
buffer `foo', which changes
with the value of
`selective-display'. The
*contents* of the buffer do not
change.
(setq selective-display nil)
=> nil
---------- Buffer: foo ----------
1 on this column
2on this column
3n this column
3n this column
2on this column
1 on this column
---------- Buffer: foo ----------
(setq selective-display 2)
=> 2
---------- Buffer: foo ----------
1 on this column
2on this column
2on this column
1 on this column
---------- Buffer: foo ----------
- Variable:
selective-display-ellipses
If this buffer-local variable
is non-`nil', then Emacs
displays `...' at the end of a
line that is followed by
invisible text. This example
is a continuation of the
previous one.
(setq selective-display-ellipses t)
=> t
---------- Buffer: foo ----------
1 on this column
2on this column ...
2on this column
1 on this column
---------- Buffer: foo ----------
You can use a display table to
substitute other text for the
ellipsis (`...'). *Note
Display Tables::.
File: elisp, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Emacs Display
Overlay Arrow
=============
The "overlay arrow" is useful for
directing the user's attention to a particular line in a buffer. For
example, in the modes used for interface to debuggers, the overlay
arrow indicates the line of code about to be executed.
- Variable: overlay-arrow-string
This variable holds the string
to display as an arrow, or
`nil' if the arrow feature is
not in use.
- Variable: overlay-arrow-position
This variable holds a marker
which indicates where to
display the arrow. It should
point at the beginning of a
line. The arrow text is
displayed at the beginning of
that line, overlaying any text
that would otherwise appear.
Since the arrow is usually
short, and the line usually
begins with indentation,
normally nothing significant is
overwritten.
The overlay string is displayed
only in the buffer which this
marker points into. Thus, only
one buffer can have an overlay
arrow at any given time.
File: elisp, Node: Temporary Displays, Next: Overlays, Prev: Overlay Arrow, Up: Emacs Display
Temporary Displays
==================
Temporary displays are used by
commands to put output into a buffer and then present it to the user
for perusal rather than for editing. Many of the help commands use
this feature.
- Special Form:
with-output-to-temp-buffer
BUFFER-NAME FORMS...
This function executes FORMS
while arranging to insert any
output they print into the
buffer named BUFFER-NAME. The
buffer is then shown in some
window for viewing, displayed
but not selected.
The string BUFFER-NAME
specifies the temporary buffer,
which need not already exist.
The argument must be a string,
not a buffer. The buffer is
erased initially (with no
questions asked), and it is
marked as unmodified after
`with-output-to-temp-buffer'
exits.
`with-output-to-temp-buffer'
binds `standard-output' to the
temporary buffer, then it
evaluates the forms in FORMS.
Output using the Lisp output
functions within FORMS goes by
default to that buffer (but
screen display and messages in
the echo area, although output
in the general sense of the
word, are not affected). *Note
Output Functions::.
The value of the last form in
FORMS is returned.
---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------
(with-output-to-temp-buffer "foo"
(print 20)
(print standard-output))
=> #<buffer foo>
---------- Buffer: foo ----------
20
#<buffer foo>
---------- Buffer: foo ----------
- Variable:
temp-buffer-show-function
The value of this variable, if
non-`nil', is called as a
function to display a help
buffer. This variable is used
by `with-output-to-temp-buffer'.
In Emacs versions 18 and
earlier, this variable was
called `temp-buffer-show-hook'.
- Function:
momentary-string-display
STRING POSITION &optional
CHAR MESSAGE
This function momentarily
displays STRING in the current
buffer at POSITION (which is a
character offset from the
beginning of the buffer). The
display remains until the next
character is typed.
If the next character the user
types is CHAR, Emacs ignores it.
Otherwise, that character
remains buffered for subsequent
use as input. Thus, typing
CHAR will simply remove the
string from the display, while
typing (say) `C-f' will remove
the string from the display and
later (presumably) move point
forward. The argument CHAR is a
space by default.
The return value of
`momentary-string-display' is
not meaningful.
If MESSAGE is non-`nil', it is
displayed in the echo area
while STRING is displayed in
the buffer. If it is `nil',
then instructions to type CHAR
are displayed there, e.g.,
`Type RET to continue editing'.
In this example, point is
initially located at the
beginning of the second line:
---------- Buffer: foo ----------
This is the contents of foo.
-!-Second line.
---------- Buffer: foo ----------
(momentary-string-display
"**** Important Message! ****" (point) ?\r
"Type RET when done reading")
=> t
---------- Buffer: foo ----------
This is the contents of foo.
**** Important Message! ****Second line.
---------- Buffer: foo ----------
---------- Echo Area ----------
Type RET when done reading
---------- Echo Area ----------
This function works by actually
changing the text in the
buffer. As a result, if you
later undo in this buffer, you
will see the message come and
go.
File: elisp, Node: Overlays, Next: Faces, Prev: Temporary Displays, Up: Emacs Display
Overlays
========
You can use "overlays" to alter
the appearance of a buffer's text on the screen. An overlay is an
object which belongs to a particular buffer, and has a specified
beginning and end. It also has properties which you can examine and
set; these affect the display of the text within the overlay.
* Menu:
* Overlay Properties:: How to read and set properties.
What properties do to the screen display.
* Managing Overlays:: Creating, moving, finding overlays.
File: elisp, Node: Overlay Properties, Next: Managing Overlays, Up: Overlays
Overlay Properties
------------------
Overlay properties are like text
properties in some respects, but the differences are more important
than the similarities. Text properties are considered a part of the
text; overlays are specifically considered not to be part of the text.
Thus, copying text between various buffers and strings preserves text,
but does not try to preserve overlays. Changing a buffer's text
properties marks the buffer as modified, while moving an overlay or
changing its properties does not.
`face'
This property controls the font
and color of text. *Note
Faces::, for more information.
This feature is temporary; in
the future, we may replace it
with other ways of specifying
how to display text.
`mouse-face'
This property is used instead
of `face' when the mouse is
within the range of the
overlay. This feature is also
temporary.
`priority'
This property's value (which
should be a nonnegative number)
determines the priority of the
overlay. The priority matters
when two or more overlays cover
the same character and both
specify a face for display; the
one whose `priority' value is
larger takes priority over the
other, and its face attributes
override the face attributes of
the lower priority overlay.
Currently, all overlays take
priority over text properties.
Please avoid using negative
priority values, as we have not
yet decided just what they
should mean.
`window'
If the `window' property is
non-`nil', then the overlay
applies only on that window.
`before-string'
This property's value is a
string to add to the display at
the beginning of the overlay.
The string does not appear in
the buffer in any sense--only
on the screen.
`after-string'
This property's value is a
string to add to the display at
the end of the overlay. The
string does not appear in the
buffer in any sense--only on
the screen.
These are the functions for
reading and writing the properties of an overlay.
- Function: overlay-get OVERLAY PROP
This function returns the value
of property PROP recorded in
OVERLAY. If OVERLAY does not
record any value for that
property, then the value is
`nil'.
- Function: overlay-put OVERLAY
PROP VALUE
This function set the value of
property PROP recorded in
OVERLAY to VALUE. It returns
VALUE.
File: elisp, Node: Managing Overlays, Prev: Overlay Properties, Up: Overlays
Managing Overlays
-----------------
- Function: make-overlay START END
&optional BUFFER
This function creates and
returns an overlay which
belongs to BUFFER and ranges
from START to END. Both START
and END must specify buffer
positions; they may be integers
or markers. If BUFFER is
omitted, the overlay is created
in the current buffer.
The return value is the overlay
itself.
- Function: overlay-start OVERLAY
This function returns the
position at which OVERLAY
starts.
- Function: overlay-end OVERLAY
This function returns the
position at which OVERLAY ends.
- Function: overlay-buffer OVERLAY
This function returns the
buffer that OVERLAY belongs to.
- Function: delete-overlay OVERLAY
This function deletes OVERLAY.
The overlay continues to exist
as a Lisp object, but ceases to
be part of the buffer it
belonged to, and ceases to have
any effect on display.
- Function: move-overlay OVERLAY
START END &optional BUFFER
This function moves OVERLAY to
BUFFER, and places its bounds
at START and END. Both
arguments START and END must
specify buffer positions; they
may be integers or markers. If
BUFFER is omitted, the overlay
stays in the same buffer.
The return value is OVERLAY.
This is the only valid way to
change the endpoints of an
overlay. Do not try modifying
the markers in the overlay by
hand, as that fails to update
other vital data structures and
can cause some overlays to be
"lost".
- Function: overlays-at POS
This function returns a list of
all the overlays that contain
position POS in the current
buffer. The list is in no
particular order. An overlay
contains position POS if it
begins at or before POS, and
ends after POS.
- Function: next-overlays-change POS
This function returns the
buffer position of the next
beginning or end of an overlay,
after POS.
File: elisp, Node: Faces, Next: Blinking, Prev: Overlays, Up: Emacs Display
Faces
=====
A "face" is a named collection of
graphical attributes: font, foreground color, background color and
optional underlining. Faces control the display of text on the screen.
Each face has its own "face id
number" which distinguishes faces at low levels within Emacs. However,
for most purposes, you can refer to faces in Lisp programs by their
names.
Each face name is meaningful for
all frames, and by default it has the same meaning in all frames. But
you can arrange to give a particular face name a special meaning in one
frame if you wish.
* Menu:
* Choosing a Face:: How Emacs decides which face to use for a character.
* Face Functions:: How to define and examine faces.
File: elisp, Node: Choosing a Face, Next: Face Functions, Up: Faces
Choosing a Face for Display
---------------------------
Here are all the ways to specify
which face to use for display of text:
* With defaults. Each frame has
a "default face", whose id
number is zero, which is used
for all text that doesn't
somehow specify another face.
* With text properties. A
character may have a `face'
property; if so, it's displayed
with that face. If the
character has a `mouse-face'
property, that is used instead
of the `face' property when the
mouse is "near enough" to the
character. *Note Special
Properties::.
* With overlays. An overlay may
have `face' and `mouse-face'
properties too; they apply to
all the text covered by the
overlay.
* With special glyphs. Each
glyph can specify a particular
face id number. *Note Glyphs::.
If these various sources together
specify more than one face for a particular character, Emacs merges the
attributes of the various faces specified. The attributes of the faces
of special glyphs come first; then come attributes of faces from
overlays, followed by those from text properties, and last the default
face.
When multiple overlays cover one
character, an overlay with higher priority overrides those with lower
priority. *Note Overlays::.
If an attribute such as the font
or a color is not specified in any of the above ways, the frame's own
font or color is used.
File: elisp, Node: Face Functions, Prev: Choosing a Face, Up: Faces
Functions for Working with Faces
--------------------------------
The attributes a face can specify
include the font, the foreground color, the background color, and
underlining. The face can also leave these unspecified by giving the
value `nil' for them.
Here are the primitives for
creating and changing faces.
- Function: make-face NAME
This function defines a new
face named NAME, initially with
all attributes `nil'. It does
nothing if there is already a
face named NAME.
- Function: face-list
This function returns a list of
all defined face names.
- Function: copy-face OLD-FACE
NEW-NAME &optional FRAME
This function defines a new
face named NEW which is a copy
of the existing face named OLD.
If there is already a face
named NEW, then it alters the
face to have the same
attributes as OLD.
If the optional argument FRAME
is given, this function applies
only to that frame. Otherwise
it applies to each frame
individually.
You can modify the attributes of
an existing face with the following functions. If you specify FRAME,
they affect just that frame; otherwise, they affect all frames as well
as the defaults that apply to new frames.
- Function: set-face-foreground
FACE COLOR &optional FRAME
- Function: set-face-background
FACE COLOR &optional FRAME
These functions set the
foreground (respectively,
background) color of face FACE
to COLOR. The argument COLOR
color should be a string, the
name of a color.
- Function: set-face-font FACE FONT
&optional FRAME
This function sets the font of
face FACE. The argument FONT
should be a string.
- Function: set-face-underline-p
FACE UNDERLINE-P &optional
FRAME
This function sets the
underline attribute of face
FACE.
- Function: invert-face FACE
&optional FRAME
Swap the foreground and
background colors of face FACE.
If the face doesn't specify
both foreground and background,
then its foreground and
background are set to the
background and foreground of
the default face.
These functions examine the
attributes of a face. If you don't specify FRAME, they refer to the
default data for new frames.
- Function: face-foreground FACE
&optional FRAME
- Function: face-background FACE
&optional FRAME
These functions return the
foreground (respectively,
background) color of face FACE.
The argument COLOR color
should be a string, the name of
a color.
- Function: face-font FACE
&optional FRAME
This function returns the name
of the font of face FACE.
- Function: face-underline-p FACE
&optional FRAME
This function returns the
underline attribute of face
FACE.
- Function: face-id-number FACE
This function returns the id
number of face FACE.
- Function: face-equal FACE1 FACE2
&optional FRAME
This returns `t' if the faces
FACE1 and FACE2 have the same
attributes for display.
- Function:
face-differs-from-default-p FACE
&optional FRAME
This returns `t' if the face
FACE displays differently from
the default face. A face is
considered to be "the same" as
the normal face if each
attribute is either the same as
that of the default face or
`nil' (meaning to inherit from
the default).
File: elisp, Node: Blinking, Next: Inverse Video, Prev: Faces, Up: Emacs Display
Blinking
========
This section describes the
mechanism by which Emacs shows a matching open parenthesis when the
user inserts a close parenthesis.
- Variable: blink-paren-function
The value of this variable
should be a function (of no
arguments) to be called
whenever a char with close
parenthesis syntax is inserted.
The value of
`blink-paren-function' may be
`nil', in which case nothing is
done.
*Please note:* this
variable was named
`blink-paren-hook' in
older Emacs versions, but
since it is not called
with the standard
convention for hooks, it
was renamed to
`blink-paren-function' in
version 19.
- Variable: blink-matching-paren
If this variable is `nil', then
`blink-matching-open' does
nothing.
- Variable:
blink-matching-paren-distance
This variable specifies the
maximum distance to scan for a
matching parenthesis before
giving up.
- Function: blink-matching-open
This function is the default
value of
`blink-paren-function'. It
assumes that point follows a
character with close
parenthesis syntax and moves
the cursor momentarily to the
matching opening character. If
that character is not already
on the screen, then its context
is shown by displaying it in
the echo area. To avoid long
delays, this function does not
search farther than
`blink-matching-paren-distance'
characters.
Here is an example of calling
this function explicitly.
(defun interactive-blink-matching-open ()
"Indicate momentarily the start of sexp before point."
(interactive)
(let ((blink-matching-paren-distance
(buffer-size))
(blink-matching-paren t))
(blink-matching-open)))
File: elisp, Node: Inverse Video, Next: Usual Display, Prev: Blinking, Up: Emacs Display
Inverse Video
=============
- User Option: inverse-video
This variable controls whether
Emacs uses inverse video for
all text on the screen.
Non-`nil' means yes, `nil'
means no. The default is `nil'.
- User Option:
mode-line-inverse-video
This variable controls the use
of inverse video for mode
lines. If it is non-`nil',
then mode lines are displayed
in inverse video (or another
suitable display mode).
Otherwise, mode lines are
displayed normal, just like the
rest of the screen. The
default is `t'.
File: elisp, Node: Usual Display, Next: Display Tables, Prev: Inverse Video, Up: Emacs Display
Usual Display Conventions
=========================
The usual display conventions
define how to display each character code. You can override these
conventions by setting up a display table (*note Display Tables::.).
Here are the usual display conventions:
* Character codes 32 through 126
map to glyph codes 32 through
126. Normally this means they
display as themselves.
* Character code 9 is a
horizontal tab. It displays as
whitespace up to a position
determined by `tab-width'.
* Character code 10 is a newline.
* All other codes in the range 0
through 31, and code 127,
display in one of two ways
according to the value of
`ctl-arrow'. If it is is
non-`nil', these codes map to
sequences of two glyphs, where
the first glyph is the ASCII
code for `^'. Otherwise, these
codes map just like the codes
in the range 128 to 255.
* Character codes 128 through 255
map to sequences of four
glyphs, where the first glyph
is the ASCII code for `\', and
the others are digit characters
representing the code in octal.
The usual display conventions
apply even when there is a display table, for any character whose entry
in the active display table is `nil'. Thus, when you set up a display
table, you need only specify the the characters for which you want
unusual behavior.
These variables affect the way
certain characters are displayed on the screen. Since they change the
number of columns the characters occupy, they also affect the
indentation functions.
- User Option: ctl-arrow
This buffer-local variable
controls how control characters
are displayed. If it is
non-`nil', they are displayed
as an uparrow followed by the
character: `^A'. If it is
`nil', they are displayed as a
backslash followed by three
octal digits: `\001'.
- Variable: default-ctl-arrow
The value of this variable is
the default value for
`ctl-arrow' in buffers that do
not override it. This is the
same as executing the following
expression:
(default-value 'ctl-arrow)
*Note Default Value::.
- User Option: tab-width
The value of this variable is
the spacing between tab stops
used for displaying tab
characters in Emacs buffers.
The default is 8. Note that
this feature is completely
independent from the
user-settable tab stops used by
the command `tab-to-tab-stop'.
*Note Indent Tabs::.
File: elisp, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Emacs Display
Display Tables
==============
You can use the "display table"
feature to control how all 256 possible character codes display on the
screen. This is useful for displaying European languages that have
letters not in the ASCII character set.
The display table maps each
character code into a sequence of "glyphs", each glyph being an image
that takes up one character position on the screen. You can also
define how to display each glyph on your terminal, using the "glyph
table".
* Menu:
* Display Table Format:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
* ISO Latin 1:: How to use display tables
to support the ISO Latin 1 character set.